---
date: 2023-11-22 17:31:00
sidebar: false
---

_November 02, 2023_

# Announcing Rspack 0.4

## Major changes

### Drop Node.js 14 support

Rspack no longer supports Node.js 14, Node.js 16+ is now required.

### Make @rspack/core as peer dependency of @rspack/cli

`@rspack/core` is now a peer dependency of `@rspack/cli` rather than a direct dependency. This means that you need to manually install `@rspack/core` with `@rspack/cli` now. aligning Rspack more closely with webpack. In the long term, the positioning of `@rspack/cli` will no longer be an out-of-the-box solution. We will align `@rspack/cli` with webpack-cli and may even directly support the use of `@rspack/core` in `webpack-cli`. We recommend [Rsbuild](https://rsbuild.rs/) as an out-of-the-box solution.

### Deprecating default transformation

`experiments.rspackFuture.disableTransformByDefault` is enabled by default in v0.4.0. For people that still need the legacy behavior, you may manually set this option to `false`.

This feature primarily addresses three categories of problems: [builtins](https://v0.rspack.rs/config/builtins) code transformation features, [target](/config/target), and custom [Rule.type](/config/module#ruletype).

1. Removal of support for some [builtins](https://v0.rspack.rs/config/builtins) features:

- [builtins.relay](https://v0.rspack.rs/config/builtins#builtinsrelay): moved to `rspackExperiments.relay`
- [builtins.react](https://v0.rspack.rs/config/builtins#builtinsreact): moved to `jsc.transform.react`
- [builtins.emotion](https://v0.rspack.rs/config/builtins#builtinsemotion): moved to `rspackExperiments.emotion`
- [builtins.pluginImport](https://v0.rspack.rs/config/builtins#builtinspluginimport): moved to `rspackExperiments.import`
- [builtins.decorator](https://v0.rspack.rs/config/builtins#builtinsdecorator): moved to `jsc.parser.decorators`
- [builtins.presetEnv](https://v0.rspack.rs/config/builtins#builtinspresetenv): moved to `jsc.env`

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'ecmascript',
              jsx: true,
            },
            transform: {
              react: {
                runtime: 'automatic',
              },
            },
          },
          rspackExperiments: {
            emotion: true, // The same as `builtins`
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
  experiments: {
    rspackFuture: {
      disableTransformByDefault: true,
    },
  },
};
```

2. [target](/config/target) will not downgrade user-side code(including `node_modules`)

```diff title="rspack.config.mjs"
export default {
  target: ["web", "es5"],
  module: {
    rules: [
      {
        test: /\.[cm]?js$/,
        exclude: /node_modules/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: "ecmascript"
            },
+           target: "es5" // Notice: `jsc.target` and `env` cannot be set at the same time.
          },
+        env: { //  Notice: `jsc.target` and `env` cannot be set at the same time.
+         targets: "chrome >= 48"
+        }
        }
        type: 'javascript/auto',
      },
    ],
  }
};
```

3. Removed non-webpack compatible [Rule.type](/config/module#ruletype)

These types have been removed:

- `"typescript"`
- `"jsx"`
- `"tsx"`

For JS-related types, only the following will be retained:

- `"javascript/auto"`
- `"javascript/esm"`
- `"javascript/dynamic"`

Refer to [this](/config/experiments#experimentsrspackfuturedisabletransformbydefault) for the complete migration guide.

Check out our previous discussion [here](https://github.com/web-infra-dev/rspack/discussions/4070).

### Deprecating builtin.react.refresh

With `experiments.rspackFuture.disableTransformByDefault` is enabled by default in v0.4.0, `builtin.react.refresh` has also been deprecated. Now we recommend using `@rspack/plugin-react-refresh` to enable react fast refresh.

```diff title="rspack.config.mjs"
+ import ReactRefreshPlugin from '@rspack/plugin-react-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  // ...
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
+                  development: isDev,
+                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
-  builtins: {
-    react: {
-      refresh: true,
-    }
-  },
  plugins: [
+    isDev && new ReactRefreshPlugin()
  ],
};
```

Checkout [here](/guide/tech/react#fast-refresh) for more details.

### Deprecating builtin:sass-loader

`builtin:sass-loader` has now been deprecated. If you are using it, migrate to `sass-loader`. Rspack will remove `builtin:sass-loader` in v0.5.0.

### Deprecating experiments.incrementalRebuild

`experiments.incrementalRebuild` has now been deprecated. Rspack will remove it in v0.5.0.

### Refactoring export API in @rspack/core

Before, some APIs should not be exported accidentally exported through re-export from @rspack/core. Now with this refactor, we clean up the export APIs from @rspack/core.

This shouldn't break anything, but if you are using unintentionally exported APIs, this may break you, and you may be using Rspack in the hacky way.

If there is a real need for removed APIs from this refactor, please raise an issue in the Rspack repository.

### Deprecating `builtins.devFriendlySplitChunks` and `experiments.newSplitChunks`

In order to full migrate to Webpack's split chunks implementation, these fields are deprecated. Rspack will remove these fields in v0.5.0.

### Enable newResolver by default

New resolver is now enabled by default.

The new resolver has passed all of [enhanced-resolve](https://www.npmjs.com/package/enhanced-resolve)'s test suite. It is 5 times faster than previous implementation, and 28 times faster than enhanced-resolve.

The new resolver can be configured to read `tsconfig.json`'s `compilerOptions.paths` and `references` field and provides better support for nested path alias. See API [resolve.tsConfig](/config/resolve#resolvetsconfig) for details.

To opt out of the new resolver, set `experiments.rspackFuture.newResolver` to `false`.

## Migration guide

There is a [migrate example](https://github.com/rspack-contrib/rstack-examples/pull/2) demonstrating how to migrate from Rspack 0.3.14 to Rspack 0.4.0.

### Choose `@rspack/cli` or `Rsbuild`?

If your application is a CSR application, we strongly encourage you to use Rsbuild instead of configuring Rspack yourself, as Rsbuild is much easier to use compared to `@rspack/cli`.

### Upgrade Node.js version

Rspack no longer supports Node.js 14 as of version 0.4.0; Node.js 16+ is now required.

### Install `@rspack/core` manually with `@rspack/cli`

```diff title=package.json
{
  "devDependencies": {
+    "@rspack/core": "0.4.0",
     "@rspack/cli": "0.4.0"
  }
}
```

### Use `builtin:swc-loader` to support module transformation

Rspack no longer transforms files by default as of version 0.4.0, you can still enable old transform behavior by the following setting

```js
{
  experiments: {
    rspackFuture: {
      disableTransformByDefault: false; // set to old transform behavior
    }
  }
}
```

But we suggest you use `builtin:swc-loader` to transform files now. More details are available in [Deprecating Default Transformation](#deprecating-default-transformation).

### Use `@rspack/plugin-react-refresh` for React applications

`builtin.react.refresh` does not work when we disable the default transformation, so you need to use `@rspack/plugin-react-refresh` to enable fast refresh. More details are available in [Deprecating builtin.react.refresh](#deprecating-builtinreactrefresh).

### Migrating builtin options to builtin plugins

In v0.4.0, Rspack deprecated some of the builtin options and migrated them to [builtin plugins](/config/plugins).

Currently, Rspack's internal plugins are divided into two categories:

- Plugins compatible with Webpack, such as DefinePlugin, ProvidePlugin, etc. This part has been fully aligned with webpack.
- Rspack-specific plugins, such as SwcJsMinimizerRspackPlugin, CopyRspackPlugin, etc.

The original `builtins.define` can be migrated as follows:

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    define: { process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) }
-  },
+  plugins: [
+    new rspack.DefinePlugin({ process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) })
+  ]
}
```

For `builtins.html`, it can be directly migrated to [HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin):

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    html: [{ template: "./index.html" }]
-  },
+  plugins: [
+    new rspack.HtmlRspackPlugin({ template: "./index.html" })
+  ]
}
```

When there are multiple configurations in `builtins.html`, multiple plugin instances can be created:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({ template: './index.html' }),
    new rspack.HtmlRspackPlugin({ template: './foo.html' }),
  ],
};
```

For `builtins.copy`, it can be directly migrated to [CopyRspackPlugin](/plugins/rspack/copy-rspack-plugin).

For the original `builtins.minifyOptions`, we provide [SwcJsMinimizerRspackPlugin](/plugins/rspack/swc-js-minimizer-rspack-plugin):

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        // minimizer configuration
      }),
    ],
  },
};
```

Other builtin options can be directly referred to the rspack [builtin plugins](/config/plugins) for migration, or completed according to the CLI prompts after upgrading to v0.4.0.
